home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 February: Tool Chest / Dev.CD Feb 99 TC.toast / Tool Chest / Interapplication Communication / ScriptableStuffItEngine / Project / MoreFiles / FullPath.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-12-02  |  9.0 KB  |  243 lines  |  [TEXT/CWIE]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    Routines for dealing with full pathnames... if you really must.
  5. **
  6. **    by Jim Luther, Apple Developer Technical Support Emeritus
  7. **
  8. **    File:        FullPath.h
  9. **
  10. **    Copyright © 1995-1998 Apple Computer, Inc.
  11. **    All rights reserved.
  12. **
  13. **    You may incorporate this sample code into your applications without
  14. **    restriction, though the sample code has been provided "AS IS" and the
  15. **    responsibility for its operation is 100% yours.  However, what you are
  16. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  17. **    after having made changes. If you're going to re-distribute the source,
  18. **    we require that you make it clear in the source that the code was
  19. **    descended from Apple Sample Code, but that you've made changes.
  20. */
  21.  
  22. #ifndef __FULLPATH__
  23. #define __FULLPATH__
  24.  
  25. #include <Types.h>
  26. #include <Files.h>
  27.  
  28. #include "Optimization.h"
  29.  
  30. #ifdef __cplusplus
  31. extern "C" {
  32. #endif
  33.  
  34. /*
  35.     IMPORTANT NOTE:
  36.     
  37.     The use of full pathnames is strongly discouraged. Full pathnames are
  38.     particularly unreliable as a means of identifying files, directories
  39.     or volumes within your application, for two primary reasons:
  40.     
  41.     •     The user can change the name of any element in the path at
  42.         virtually any time.
  43.     •    Volume names on the Macintosh are *not* unique. Multiple
  44.         mounted volumes can have the same name. For this reason, the use of
  45.         a full pathname to identify a specific volume may not produce the
  46.         results you expect. If more than one volume has the same name and
  47.         a full pathname is used, the File Manager currently uses the first
  48.         mounted volume it finds with a matching name in the volume queue.
  49.     
  50.     In general, you should use a file’s name, parent directory ID, and
  51.     volume reference number to identify a file you want to open, delete,
  52.     or otherwise manipulate.
  53.     
  54.     If you need to remember the location of a particular file across
  55.     subsequent system boots, use the Alias Manager to create an alias
  56.     record describing the file. If the Alias Manager is not available, you
  57.     can save the file’s name, its parent directory ID, and the name of the
  58.     volume on which it’s located. Although none of these methods is
  59.     foolproof, they are much more reliable than using full pathnames to
  60.     identify files.
  61.     
  62.     Nonetheless, it is sometimes useful to display a file’s full pathname
  63.     to the user. For example, a backup utility might display a list of full
  64.     pathnames of files as it copies them onto the backup medium. Or, a
  65.     utility might want to display a dialog box showing the full pathname of
  66.     a file when it needs the user’s confirmation to delete the file. No
  67.     matter how unreliable full pathnames may be from a file-specification
  68.     viewpoint, users understand them more readily than volume reference
  69.     numbers or directory IDs. (Hint: Use the TruncString function from
  70.     TextUtils.h with truncMiddle as the truncWhere argument to shorten
  71.     full pathnames to a displayable length.)
  72.     
  73.     The following technique for constructing the full pathname of a file is
  74.     intended for display purposes only. Applications that depend on any
  75.     particular structure of a full pathname are likely to fail on alternate
  76.     foreign file systems or under future system software versions.
  77. */
  78.  
  79. /*****************************************************************************/
  80.  
  81. pascal    OSErr    GetFullPath(short vRefNum,
  82.                             long dirID,
  83.                             ConstStr255Param name,
  84.                             short *fullPathLength,
  85.                             Handle *fullPath);
  86. /*    ¶ Get a full pathname to a volume, directory or file.
  87.     The GetFullPath function builds a full pathname to the specified
  88.     object. The full pathname is returned in the newly created handle
  89.     fullPath and the length of the full pathname is returned in
  90.     fullPathLength. Your program is responsible for disposing of the
  91.     fullPath handle.
  92.     
  93.     Note that a full pathname can be made to a file/directory that does not
  94.     yet exist if all directories up to that file/directory exist. In this case,
  95.     GetFullPath will return a fnfErr.
  96.     
  97.     vRefNum            input:    Volume specification.
  98.     dirID            input:    Directory ID.
  99.     name            input:    Pointer to object name, or nil when dirID
  100.                             specifies a directory that's the object.
  101.     fullPathLength    output:    The number of characters in the full pathname.
  102.                             If the function fails to create a full
  103.                             pathname, it sets fullPathLength to 0.
  104.     fullPath        output:    A handle to the newly created full pathname
  105.                             buffer. If the function fails to create a
  106.                             full pathname, it sets fullPath to NULL.
  107.     
  108.     Result Codes
  109.         noErr                0        No error    
  110.         nsvErr                -35        No such volume
  111.         ioErr                -36        I/O error
  112.         bdNamErr            -37        Bad filename
  113.         fnfErr                -43        File or directory does not exist (fullPath
  114.                                     and fullPathLength are still valid)
  115.         paramErr            -50        No default volume
  116.         memFullErr            -108    Not enough memory
  117.         dirNFErr            -120    Directory not found or incomplete pathname
  118.         afpAccessDenied        -5000    User does not have the correct access
  119.         afpObjectTypeErr    -5025    Directory not found or incomplete pathname
  120.     
  121.     __________
  122.     
  123.     See also:    FSpGetFullPath
  124. */
  125.  
  126. /*****************************************************************************/
  127.  
  128. pascal    OSErr    FSpGetFullPath(const FSSpec *spec,
  129.                                short *fullPathLength,
  130.                                Handle *fullPath);
  131. /*    ¶ Get a full pathname to a volume, directory or file.
  132.     The GetFullPath function builds a full pathname to the specified
  133.     object. The full pathname is returned in the newly created handle
  134.     fullPath and the length of the full pathname is returned in
  135.     fullPathLength. Your program is responsible for disposing of the
  136.     fullPath handle.
  137.     
  138.     Note that a full pathname can be made to a file/directory that does not
  139.     yet exist if all directories up to that file/directory exist. In this case,
  140.     FSpGetFullPath will return a fnfErr.
  141.     
  142.     spec            input:    An FSSpec record specifying the object.
  143.     fullPathLength    output:    The number of characters in the full pathname.
  144.                             If the function fails to create a full pathname,
  145.                             it sets fullPathLength to 0.
  146.     fullPath        output:    A handle to the newly created full pathname
  147.                             buffer. If the function fails to create a
  148.                             full pathname, it sets fullPath to NULL.
  149.     
  150.     Result Codes
  151.         noErr                0        No error    
  152.         nsvErr                -35        No such volume
  153.         ioErr                -36        I/O error
  154.         bdNamErr            -37        Bad filename
  155.         fnfErr                -43        File or directory does not exist (fullPath
  156.                                     and fullPathLength are still valid)
  157.         paramErr            -50        No default volume
  158.         memFullErr            -108    Not enough memory
  159.         dirNFErr            -120    Directory not found or incomplete pathname
  160.         afpAccessDenied        -5000    User does not have the correct access
  161.         afpObjectTypeErr    -5025    Directory not found or incomplete pathname
  162.     
  163.     __________
  164.     
  165.     See also:    GetFullPath
  166. */
  167.  
  168. /*****************************************************************************/
  169.  
  170. pascal OSErr FSpLocationFromFullPath(short fullPathLength,
  171.                                      const void *fullPath,
  172.                                      FSSpec *spec);
  173. /*    ¶ Get a FSSpec from a full pathname.
  174.     The FSpLocationFromFullPath function returns a FSSpec to the object
  175.     specified by full pathname. This function requires the Alias Manager.
  176.     
  177.     fullPathLength    input:    The number of characters in the full pathname
  178.                             of the target.
  179.     fullPath        input:    A pointer to a buffer that contains the full
  180.                             pathname of the target. The full pathname
  181.                             starts with the name of the volume, includes
  182.                             all of the directory names in the path to the
  183.                             target, and ends with the target name.
  184.     spec            output:    An FSSpec record specifying the object.
  185.     
  186.     Result Codes
  187.         noErr                0        No error
  188.         nsvErr                -35        The volume is not mounted
  189.         fnfErr                -43        Target not found, but volume and parent
  190.                                     directory found
  191.         paramErr            -50        Parameter error
  192.         usrCanceledErr        -128    The user canceled the operation
  193.     
  194.     __________
  195.     
  196.     See also:    LocationFromFullPath
  197. */
  198.  
  199. /*****************************************************************************/
  200.  
  201. pascal OSErr LocationFromFullPath(short fullPathLength,
  202.                                   const void *fullPath,
  203.                                   short *vRefNum,
  204.                                   long *parID,
  205.                                   Str31 name);
  206. /*    ¶ Get an object's location from a full pathname.
  207.     The LocationFromFullPath function returns the volume reference number,
  208.     parent directory ID and name of the object specified by full pathname.
  209.     This function requires the Alias Manager.
  210.     
  211.     fullPathLength    input:    The number of characters in the full pathname
  212.                             of the target.
  213.     fullPath        input:    A pointer to a buffer that contains the full
  214.                             pathname of the target. The full pathname starts
  215.                             with the name of the volume, includes all of
  216.                             the directory names in the path to the target,
  217.                             and ends with the target name.
  218.     vRefNum            output:    The volume reference number.
  219.     parID            output:    The parent directory ID of the specified object.
  220.     name            output:    The name of the specified object.
  221.     
  222.     Result Codes
  223.         noErr                0        No error
  224.         nsvErr                -35        The volume is not mounted
  225.         fnfErr                -43        Target not found, but volume and parent
  226.                                     directory found
  227.         paramErr            -50        Parameter error
  228.         usrCanceledErr        -128    The user canceled the operation
  229.     
  230.     __________
  231.     
  232.     See also:    FSpLocationFromFullPath
  233. */
  234.  
  235. /*****************************************************************************/
  236.  
  237. #ifdef __cplusplus
  238. }
  239. #endif
  240.  
  241. #include "OptimizationEnd.h"
  242.  
  243. #endif    /* __FULLPATH__ */